Этот материал помогает аналитикам описывать и проверять требования к доступу в системе: от входа пользователя до контроля прав. Если тебе нужно быстро развести термины, см. также файл auth-vs-auth.
Важно разделять два слоя:
users:read).Во многих API используется двухтокенная схема. После успешного входа система выдает временные ключи (токены), чтобы клиент мог обращаться к защищенным ресурсам без повторного ввода пароля.
| Тип токена | Назначение | Время жизни | Безопасность |
|---|---|---|---|
| Access Token | Доступ к ресурсам (API, данные профиля). | Короткое (например 5–30 минут) | Обычно передается в заголовке Authorization: Bearer <token>; на клиенте предпочтительно хранить в памяти приложения, чтобы снизить риск XSS-кражи. |
| Refresh Token | Получение нового access token, когда старый истек. | Длинное (например 7–30 дней) | Типично хранится в защищенном контейнере (часто HttpOnly cookie) и используется только для обращения к эндпоинту обновления. |
Ключевой смысл: access token живет мало, поэтому его компрометация ограничена по времени. refresh token живет долго, поэтому к нему требования строже (ротация, отзыв, привязка к устройству/сессии).
⚠️ Никогда не храните пароли в открытом виде!
Пароли должны проходить через процесс хэширования – одностороннего криптографического преобразования. Популярные и надежные алгоритмы – bcrypt и Argon2.
Что важно для аналитика в требованиях:
Для повышения безопасности используется двухфакторная аутентификация (2FA). Это метод, требующий подтверждения личности двумя разными способами:
OTP (One-Time Password) — одноразовый код, действующий короткое время (обычно 30–300 секунд). Практически встречаются:
Что стоит зафиксировать в требованиях:
Sequence-диаграмма удобна, чтобы согласовать поведение фронта/бэка/БД и проговорить ошибки.
User: Пользователь.App: Клиентское приложение (web/mobile).Auth Service: Сервис аутентификации.Database: База данных.POST /api/v1/auth/login {email, password}200 OK {access_token, refresh_token}SELECT ... FROM users WHERE email = ?alt: ветвления (успех/ошибка).opt: опциональные шаги.loop: повторения (например, несколько попыток).sequenceDiagram participant User participant App participant Auth as Auth Service participant DB as Database App->>Auth: POST /api/v1/auth/login {email, password} Auth->>DB: SELECT id, password_hash, status FROM users WHERE email = ? alt user exists and password ok Auth->>DB: INSERT INTO refresh_tokens (user_id, token_hash, expires_at, device_id) VALUES (...) Auth-->>App: 200 OK {access_token, refresh_token} else invalid credentials Auth-->>App: 401 Unauthorized else user blocked Auth-->>App: 403 Forbidden end
| Код | Название | Когда использовать |
|---|---|---|
| 200 OK | Успех | Успешный вход, обновление токена, получение профиля. |
| 201 Created | Создано | Регистрация пользователя, создание сессии/устройства (если моделируется как ресурс). |
| 204 No Content | Нет содержимого | Успешный logout (если тело ответа не требуется). |
| 400 Bad Request | Неверный запрос | Не хватает обязательных полей, неверный формат payload. |
| 401 Unauthorized | Не аутентифицирован | Неверный пароль, отсутствует/невалиден/истек access token. |
| 403 Forbidden | Запрещено | Аутентификация есть, но прав на действие нет (RBAC/ABAC), или пользователь заблокирован. |
| 409 Conflict | Конфликт | Попытка зарегистрировать email, который уже существует (если так принято в продукте). |
| 429 Too Many Requests | Слишком много запросов | Rate limiting, защита от brute force/credential stuffing. |
| Операция | Пример SQL | Зачем это нужно |
|---|---|---|
| Создание пользователя | INSERT INTO users (...) VALUES (...) |
Регистрация. |
| Поиск пользователя | SELECT id, password_hash, status FROM users WHERE email = ? |
Вход в систему. |
| Фиксация неуспешной попытки | UPDATE users SET failed_attempts = failed_attempts + 1 WHERE id = ? |
Anti-bruteforce, блокировки. |
| Сохранение refresh token | INSERT INTO refresh_tokens (...) VALUES (...) |
Создание «длинной» сессии/устройства. |
| Ротация refresh token | UPDATE refresh_tokens SET token_hash = ?, rotated_at = ? WHERE id = ? |
Снижение риска при компрометации. |
| Отзыв токенов | DELETE FROM refresh_tokens WHERE user_id = ? |
Logout «со всех устройств» или отзыв при инциденте. |
| Риск/угроза | Типовые меры защиты |
|---|---|
| Brute force / credential stuffing | Rate limiting, CAPTCHA по риск-сигналам, блокировки/заморозка, уведомления, мониторинг. |
| CSRF | Актуально, когда аутентификация опирается на cookies: SameSite, CSRF-токены, запрет кросс-сайтовых запросов где возможно. Если access token передается только в Authorization header, CSRF-риски обычно ниже, но XSS важнее. |
| XSS | Экранирование/санитизация, CSP, минимизация хранения токенов в доступных JS-хранилищах. HttpOnly cookie защищает от чтения токена JS-кодом, но не является «лекарством от XSS» в целом. |
| SQL Injection | Параметризованные запросы/ORM, валидация входных данных. |
| Кража refresh token | Хешировать refresh token в БД, привязка к устройству, ротация, обнаружение повторного использования (reuse detection). |
401 и 403, сообщения без утечек (не раскрывать «пользователь существует/не существует» без нужды).